home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / place.n < prev    next >
Encoding:
Text File  |  1994-09-20  |  11.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. place(n)                   Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      place - Geometry manager for fixed or rubber-sheet placement  |
  12.  
  13. SYNOPSIS                                                           |
  14.      place _w_i_n_d_o_w _o_p_t_i_o_n _v_a_l_u_e ?_o_p_t_i_o_n _v_a_l_u_e ...?                  |
  15.  
  16.      place configure _w_i_n_d_o_w _o_p_t_i_o_n _v_a_l_u_e ?_o_p_t_i_o_n _v_a_l_u_e ...?        |
  17.  
  18.      place forget _w_i_n_d_o_w                                           |
  19.  
  20.      place info _w_i_n_d_o_w                                             |
  21.  
  22.      place slaves _w_i_n_d_o_w                                           |
  23. _________________________________________________________________
  24.  
  25.  
  26. DESCRIPTION
  27.      The placer is a geometry manager for Tk.  It provides simple
  28.      fixed placement of windows, where you specify the exact size
  29.      and location of one window, called the _s_l_a_v_e, within another
  30.      window,   called  the  _m_a_s_t_e_r.   The  placer  also  provides
  31.      rubber-sheet placement, where you specify the size and loca-
  32.      tion  of the slave in terms of the dimensions of the master,
  33.      so that the slave changes size and location in  response  to
  34.      changes  in  the  size  of  the  master.  Lastly, the placer
  35.      allows you to mix these styles of  placement  so  that,  for
  36.      example,  the slave has a fixed width and height but is cen-
  37.      tered inside the master.
  38.  
  39.      If the first argument to the place command is a window  path
  40.      name  or  configure then the command arranges for the placer
  41.      to manage the geometry of a slave whose path name is _w_i_n_d_o_w.
  42.      The  remaining arguments consist of one or more _o_p_t_i_o_n-_v_a_l_u_e
  43.      pairs that specify the way in  which  _w_i_n_d_o_w's  geometry  is
  44.      managed.  If the placer is already managing _w_i_n_d_o_w, then the
  45.      _o_p_t_i_o_n-_v_a_l_u_e pairs modify the configuration for _w_i_n_d_o_w.   In
  46.      this  form  the  place  command  returns  an empty string as
  47.      result.  The following _o_p_t_i_o_n-_v_a_l_u_e pairs are supported:
  48.  
  49.      -in _m_a_s_t_e_r
  50.           _M_a_s_t_e_r specifes the path name of the window relative to
  51.           which  _w_i_n_d_o_w  is  to be placed.  _M_a_s_t_e_r must either be
  52.           _w_i_n_d_o_w's parent or a descendant of _w_i_n_d_o_w's parent.  In
  53.           addition, _m_a_s_t_e_r and _w_i_n_d_o_w must both be descendants of
  54.           the same  top-level  window.   These  restrictions  are
  55.           necessary  to guarantee that _w_i_n_d_o_w is visible whenever
  56.           _m_a_s_t_e_r is visible.  If this option isn't specified then
  57.           the master defaults to _w_i_n_d_o_w's parent.
  58.  
  59.      -x _l_o_c_a_t_i_o_n
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. place(n)                   Tk Commands
  71.  
  72.  
  73.  
  74.           _L_o_c_a_t_i_o_n specifies the x-coordinate within  the  master
  75.           window of the anchor point for _w_i_n_d_o_w.  The location is
  76.           specified in  screen  units  (i.e.  any  of  the  forms
  77.           accepted  by  Tk_GetPixels) and need not lie within the
  78.           bounds of the master window.
  79.  
  80.      -relx _l_o_c_a_t_i_o_n
  81.           _L_o_c_a_t_i_o_n specifies the x-coordinate within  the  master
  82.           window  of  the  anchor point for _w_i_n_d_o_w.  In this case
  83.           the location is specified in a relative  fashion  as  a
  84.           floating-point  number:   0.0  corresponds  to the left
  85.           edge of the master and 1.0  corresponds  to  the  right
  86.           edge  of the master.  _L_o_c_a_t_i_o_n need not be in the range
  87.           0.0-1.0.
  88.  
  89.      -y _l_o_c_a_t_i_o_n
  90.           _L_o_c_a_t_i_o_n specifies the y-coordinate within  the  master
  91.           window of the anchor point for _w_i_n_d_o_w.  The location is
  92.           specified in  screen  units  (i.e.  any  of  the  forms
  93.           accepted  by  Tk_GetPixels) and need not lie within the
  94.           bounds of the master window.
  95.  
  96.      -rely _l_o_c_a_t_i_o_n
  97.           _L_o_c_a_t_i_o_n specifies the y-coordinate within  the  master
  98.           window  of  the  anchor point for _w_i_n_d_o_w.  In this case
  99.           the value is specified  in  a  relative  fashion  as  a
  100.           floating-point number:  0.0 corresponds to the top edge
  101.           of the master and 1.0 corresponds to the bottom edge of
  102.           the master.  _L_o_c_a_t_i_o_n need not be in the range 0.0-1.0.
  103.  
  104.      -anchor _w_h_e_r_e
  105.           _W_h_e_r_e specifies which point of _w_i_n_d_o_w is  to  be  posi-
  106.           tioned  at  the  (x,y) location selected by the -x, -y,
  107.           -relx, and -rely options.  The anchor point is in terms
  108.           of  the  outer  area of _w_i_n_d_o_w including its border, if
  109.           any.  Thus if _w_h_e_r_e is se then the  lower-right  corner
  110.           of _w_i_n_d_o_w's border will appear at the given (x,y) loca-
  111.           tion in the master.  The anchor  position  defaults  to
  112.           nw.
  113.  
  114.      -width _s_i_z_e
  115.           _S_i_z_e specifies the width for  _w_i_n_d_o_w  in  screen  units
  116.           (i.e.  any of the forms accepted by Tk_GetPixels).  The
  117.           width will be the outer width of _w_i_n_d_o_w  including  its
  118.           border,  if  any.  If _s_i_z_e is an empty string, or if no
  119.           -width or -relwidth option is specified, then the width
  120.           requested internally by the window will be used.
  121.  
  122.      -relwidth _s_i_z_e
  123.           _S_i_z_e specifies the width for _w_i_n_d_o_w.  In this case  the
  124.           width  is specified as a floating-point number relative
  125.           to the width of the master: 0.5 means  _w_i_n_d_o_w  will  be
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. place(n)                   Tk Commands
  137.  
  138.  
  139.  
  140.           half  as wide as the master, 1.0 means _w_i_n_d_o_w will have
  141.           the same width as the master, and so on.
  142.  
  143.      -height _s_i_z_e
  144.           _S_i_z_e specifies the height for _w_i_n_d_o_w  in  screen  units
  145.           (i.e.  any of the forms accepted by Tk_GetPixels).  The
  146.           height will be the outer dimension of _w_i_n_d_o_w  including
  147.           its  border, if any.  If _s_i_z_e is an empty string, or if
  148.           no -height or -relheight option is specified, then  the
  149.           height requested internally by the window will be used.
  150.  
  151.      -relheight _s_i_z_e
  152.           _S_i_z_e specifies the height for _w_i_n_d_o_w.  In this case the
  153.           height is specified as a floating-point number relative
  154.           to the height of the master: 0.5 means _w_i_n_d_o_w  will  be
  155.           half  as high as the master, 1.0 means _w_i_n_d_o_w will have
  156.           the same height as the master, and so on.
  157.  
  158.      -bordermode _m_o_d_e
  159.           _M_o_d_e determines the degree to which borders within  the
  160.           master  are  used  in  determining the placement of the
  161.           slave.  The default and most common  value  is  inside.
  162.           In  this case the placer considers the area of the mas-
  163.           ter to be the innermost area of the master, inside  any
  164.           border:  an  option  of  -x  0  corresponds  to  an  x-
  165.           coordinate just inside the  border  and  an  option  of
  166.           -relwidth  1.0  means  _w_i_n_d_o_w will fill the area inside
  167.           the master's border.   If  _m_o_d_e  is  outside  then  the
  168.           placer  considers the area of the master to include its
  169.           border; this mode is typically used when placing _w_i_n_d_o_w
  170.           outside  its  master,  as  with  the  options -x 0 -y 0
  171.           -anchor ne.  Lastly, _m_o_d_e may be specified  as  ignore,
  172.           in  which  case  borders  are ignored:  the area of the
  173.           master is considered to be its official X  area,  which
  174.           includes any internal border but no external border.  A
  175.           bordermode of ignore is probably not very useful.
  176.  
  177.      If the same value is specified separately with two different
  178.      options,  such  as -x and -relx, then the most recent option
  179.      is used and the older one is ignored.
  180.  
  181.      The place slaves command returns a list  of  all  the  slave  |
  182.      windows  for  which  _w_i_n_d_o_w  is the master.  If there are no
  183.      slaves for _w_i_n_d_o_w then an empty string is returned.
  184.  
  185.      The place forget command causes the placer to stop  managing
  186.      the  geometry  of  _w_i_n_d_o_w.  As a side effect of this command
  187.      _w_i_n_d_o_w will be unmapped so that it  doesn't  appear  on  the
  188.      screen.   If  _w_i_n_d_o_w  isn't  currently managed by the placer
  189.      then the command has no effect.   Place  forget  returns  an
  190.      empty string as result.
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. place(n)                   Tk Commands
  203.  
  204.  
  205.  
  206.      The place info command returns a  list  giving  the  current
  207.      configuration  of _w_i_n_d_o_w.  The list consists of _o_p_t_i_o_n-_v_a_l_u_e
  208.      pairs in exactly the same form as might be specified to  the
  209.      place  configure  command.  If the configuration of a window
  210.      has been retrieved with place info, that  configuration  can
  211.      be  restored  later by first using place forget to erase any
  212.      existing information for the window and then invoking  place
  213.      configure with the saved information.
  214.  
  215.  
  216. FINE POINTS
  217.      It is not necessary for the master window to be  the  parent
  218.      of the slave window.  This feature is useful in at least two
  219.      situations.  First, for complex window layouts it means  you
  220.      can  create  a hierarchy of subwindows whose only purpose is
  221.      to assist in the layout of the  parent.   The  ``real  chil-
  222.      dren''  of the parent (i.e. the windows that are significant
  223.      for the application's user interface) can be children of the
  224.      parent  yet  be  placed  inside the windows of the geometry-
  225.      management hierarchy.  This means that the path names of the
  226.      ``real  children''  don't  reflect  the  geometry-management
  227.      hierarchy and users can specify options for the  real  chil-
  228.      dren  without  being aware of the structure of the geometry-
  229.      management hierarchy.
  230.  
  231.      A second reason for  having  a  master  different  than  the
  232.      slave's  parent  is to tie two siblings together.  For exam-
  233.      ple, the placer can be used to force a window always  to  be
  234.      positioned centered just below one of its siblings by speci-
  235.      fying the configuration
  236.  
  237.           -in _s_i_b_l_i_n_g -relx 0.5 -rely 1.0 -anchor n -bordermode outside
  238.  
  239.      Whenever the sibling is  repositioned  in  the  future,  the
  240.      slave will be repositioned as well.
  241.  
  242.      Unlike many other geometry managers (such as the packer) the
  243.      placer  does not make any attempt to manipulate the geometry
  244.      of the master windows or the parents of slave windows  (i.e.
  245.      it doesn't set their requested sizes).  To control the sizes
  246.      of these windows, make them windows like frames and canvases
  247.      that provide configuration options for this purpose.
  248.  
  249.  
  250. KEYWORDS
  251.      geometry manager, height, location,  master,  place,  rubber
  252.      sheet, slave, width
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.